/**
 * <h3>IAdvertisementService</h3>
 * <p> 广告信息管理服务接口 </p>
 *
 * <h3>功能描述</h3>
 * <p> 定义广告信息增删改查等基础业务操作，供实现类完成具体数据库交互逻辑 </p>
 * <p> 接口基于 MyBatis Plus 的 {@link IService} 扩展，统一规范数据访问层行为 </p>
 *
 * <h3>元数据</h3>
 * <ul>
 *    <li> 作者：郭强 </li>
 *    <li> 创建日期：2025年05月22日 21:15:20 </li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *    <li> 参考链接：<a href="https://example.com">官方网页</a></li>
 *    <li> 示例代码：{@code new IAdvertisementService()} </li>
 * </ul>
 *
 * @apiNote 接口方法需保证事务一致性与线程安全；实际实现应避免直接new
 * @implSpec 继承自 {@link IService<AdvertisementDTO>}，扩展了按条件查询、按ID获取等方法
 * @since 1.0.0
 */

package com.dnndo.system.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.dnndo.system.domain.Advertisement;
import com.dnndo.system.domain.dto.AdvertisementDTO;

import java.util.List;

/**
 * 广告服务接口
 */
public interface IAdvertisementService extends IService<AdvertisementDTO> {

    /**
     * 根据条件分页查询广告列表
     *
     * @param dto 广告查询条件封装对象，包含广告名称、类型、省份等过滤条件
     * @return List<AdvertisementDTO> 符合条件的广告信息列表
     * @see AdvertisementDTO
     */
    List<Advertisement> selectAdvertisementList(AdvertisementDTO dto);

    /**
     * 根据广告ID获取详细信息
     *
     * @param advertisementId 广告唯一标识符
     * @return Advertisement 包含广告详细信息的数据对象
     * @see AdvertisementDTO
     */
    AdvertisementDTO selectAdvertisementListById(Long advertisementId);

    /**
     * 修改已有广告信息
     *
     * @param advertisementDTO 包含更新字段的广告数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see AdvertisementDTO
     */
    int updateAdvertisementById(AdvertisementDTO advertisementDTO);

    /**
     * 新增广告信息
     *
     * @param advertisementDTO 包含新增字段的广告数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see AdvertisementDTO
     */
    int insertAdvertisement(AdvertisementDTO advertisementDTO);

    /**
     * 删除指定ID的广告信息
     *
     * @param advertisementId 要删除的广告唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see AdvertisementDTO
     */
    int deleteAdvertisementById(Integer advertisementId);
}
